--------------------------------------------------------------------------------
A dream in the making for roughly 40 years? Yeah - that's it...and what you see
here in this archive is the result.
--------------------------------------------------------------------------------

For a very, very long time, I had wondered if there was a way to do page flip-
ping (or more accurately, double buffering) on a CoCo 3 in BASIC. My greatest
stumbling block, since I was a kid, was understanding how the MMU worked. I
could never wrap my head completely around it.

Over time and as I grew older, I learned more...but that MMU just dogged on me,
but with a bit of osmosis, and the help of various reference material (partic-
ularly Lomont's memory maps, and the Unraveled series)...I was beginning to
understand it. Not perfectly, but something was clicking in my brain, mushy as
it is.

But I still didn't think that I knew enough in order to do what I thought could
be done - at least with a 512K CoCo 3. That much was really true, when someone,
I forget who on the FB forum pointed it out to me, but I'm glad they did...

...they posted over to me this Stack Overflow question and answer:

https://retrocomputing.stackexchange.com/questions/26365/how-do-you-implement-double-buffering-on-a-coco-3-320x192x16-screen-in-basic/

It was that link that broke the dam open, and now I understand how things work
much better than ever!

--------------------------------------------------------------------------------

As some of you know, I played around with the example which "Captain Obvlious"
provided, and I posted a few "demo programs" derived from those examples, and
even a demo disk image, which can be found in the files section. It led me to
some thinking, to some schemin' - and along the way, I learned even more bits
of peculiar things about the CoCo 3 (maybe they've been mentioned before, or
maybe people know about them, but don't consider them important - in the grand
scheme of things, they really aren't, if you're just doing ordinary SECB
graphics).

After I got my feet wet with that simple demo, I knew I could do what I have
wanted to do for a long while, and I'm sure you can guess at what that is based
on the filenames on the disk images, right?

Yep - a "spinning wireframe cube"...

Now - don't get too excited - it isn't exactly a speed champ...but it is really
3D (perspective correct) - mainly from code I wrote a long time ago by porting
code from one of Lee Adam's graphics books (probably "High Performance Interact-
ive Graphics" - he had a ton of them published). For me, it was a very access-
ible way for me to learn 3D graphics; I have a few of the demos from the book
ported to the CoCo 3 - maybe someday I'll upload them.

But I really just wanted a way to display a 3D wireframe cube - so I dug around
in my archive, and found the example I needed. A little bit of work, etc - and
I got it bashed into what you see on these disk images.

--------------------------------------------------------------------------------

Let's first start with the 512K disk image. I must caution you, that I've only
tried everything using XRoar Online:

    https://www.6809.org.uk/xroar/online/
    
I've not tried any of this with any other emulator, and certain not with actual
hardware. So if you do try it elsewhere, and it doesn't work like you think it
should...well, let me know...I can't guarantee a fix or anything, but I will
take note and try to figure something out. Fair enough? Ok.

So...on the 512K disk, you'll see three programs:

    WIRECUBE.BAS (gee, I wonder what that is?)
    HS4PFLIP.BAS
    HS2PFLIP.BAS
    
These programs will -only- run on a 512K (or better) machine; don't try 'em on
a 128K machine, it won't work.

The programs "HS2PFLIP.BAS" and "HS2PFLIP.BAS" are both slightly refined (very
slightly...) versions of the ones I already posted, for HSCREEN 2 (320 x 192 x 
16 colors), and for HSCREEN 4 (640 x 192 x 4 colors). Both of those screens need
four 8K pages in memory to store and display them; in order to do double buffer-
ing, you need double that amount. On a 128K CoCo 3, there just isn't enough con-
tiguous RAM to accomodate such a thing, unfortunately. I gave it a lot of 
thought, I tried to come up with a scheme...but because you need all of the RAM
to be "following each other" (because you display your image by altering a GIME
register that points to a part of the larger 512K address space), it just isn't
possible otherwise (now, if there was a way to tell the MMU to build a display
space from different blocks scattered around the address space, then you could
almost do it...almost; there is "just enough" memory in a variety of areas that
you could maybe fit it in - but since as far as I know, you can do that kind of
a thing, it's moot to think about).

As for the third program, "WIRECUBE.BAS" - well, that's a much more refined
version of what Captain Obvlious showed; besides the 3D projection and rotation
of a cube (very, very slow rotation...sigh)...I managed to make the double-
buffering part pretty much "dead easy" - just GOSUB to the routine, draw your
image, do that again and again in a loop - and that's all you need to do; the
routine handles everything else for you! It is really that simple; take a look
at the code if you don't believe me...

--------------------------------------------------------------------------------

Now - take a look at the other floppy image...the one for a 128K machine. Wait,
did I say 128K? Didn't Captain Obvlious say it couldn't work on such a machine?

Well...he wasn't wrong...as long as we are talking about the 320 x 192 x 16 col-
ors mode...but what about HSCREEN 1?

That, my friends, we can do.

Because it's a 320 x 192 x 4 color mode, it takes up only half the amount of
RAM the 16 color mode does; the same applies to HSCREEN 3 (640 x 192 x2 colors).

Those modes only need two 8K blocks of RAM - and we have four available on the
128K CoCo 3! Sure, it isn't as colorful, but we got along fine with similar
modes on the CoCo 2 (and I should note, there are artifact colors available!).

So if you can live with those limitations - you can do double-buffering on the
128K CoCo 3.

But I did find one "catch"...stumped me for a short bit, but then I thought that
it was either a bug or something in the ROM. Honestly, I don't know if it is or
isn't; in the normal course of graphics on the CoCo 3, you'd never know it was
an issue. Until I tried to do something.

So - you'll see on the 128K disk image that there are three very similar pieces
of code like that on the 512K image. Just for HSCREEN 1 and 3, instead of 2 and
4. The basic page flipping demos, much like their 512K cousins, essentially do
the following:

    1. Two buffers are denoted; one that is visible, and one that is hidden.
    
    2. While the visible one is being display, registers on the GIME are 
       updated so that all manipulation with the regular BASIC command occur
       on the "hidden page".

    3. One thing that has to be done, before you draw on the hidden page, is
       you need to get rid of what was there from before. Captain Obvlious
       used HCLS, but that is slow for a single line, so I had updated the
       4/16 color versions to save the prior line's cordinates, and just
       erased the line - not the whole screen. That was much faster.
       
    4. So...that code got carried over to the 128K versions, and they worked
       nicely. Not a problem. Great - so lets do the cube, right?
       
    5. Well, when I decided to do the cube, I knew for the demo that I didn't
       want to go to the trouble of have two "copies" of the line information
       for the cube; it's only 8 vertices, of course, but I wanted to get the
       demo done and working fast, and the fastest way to do that was to clear
       the entire screen (using HCLS).
       
    6. That worked great on the 512K version, with screens that used four 8K
       chunks of RAM...
       
But then when I tried doing it on the 128K version...I ran into a very interest-
ing issue...it took me a bit to understand what was happening, and a quick look
at the memory map and the Unraveled book for the CoCo 3 showed me exactly what 
I suspected:

    HCLS clears all four 8K chunks!

So - long story short (lol) - I had to patch the HCLS command to make it only
clear what I wanted it to clear - either the first two 8K chunks, or the second
pair; check out the code, pull out Lomont's memory map, plus the Unraveled book,
and with the comments I put in the code, you should be able to understand what
I did and why I had to do it (if you want to see what it was doing without the
patch, you can remove the POKES and just do the HCLS "bare" - just make sure the
original default values are in place for the full effect; if in doubt, do a hard
reset).

--------------------------------------------------------------------------------

So - there you have it. Is there anything that is useful about it? Would it help
for games? Maybe in a compiled program? CMOC? Maybe UgBASIC (though I think it
already has something like that built in - I'm not sure).

I know that I've gone thru my archive, and found some old bits of code I wrote
as a kid that flicker badly, but run fairly well when they were compiled using
CBASIC-3 - so I do think there is potential with the technique.

Even with plain BASIC, the technique could probably be useful; SECB's HGET/HPUT
is fairly decent.

Maybe it could be applied for less "action" style games, and more "turn based"?

Perhaps graphic adventures in BASIC could benefit? It's honestly too bad that
this kind of thing wasn't published "back in the day" - but then again, it isn't
immediately intuitive, until you understand the parts and the technique, and
that kind of thing wasn't as readily available back then (and I had no access to
the Unraveled series, or a decent memory map).

--------------------------------------------------------------------------------

Well - I hope you enjoy these programs as much as I did creating them. Again, if
you have any suggestions, ideas on speeding things up, etc - pass 'em along. I
know there is plenty of opportunities with all parts of it (especially the 3D
code; I've read more than once that Lee Adam's stuff is not the greatest from a 
performance standpoint, but it was easily approachable for learning, and I ap-
preciated that part).

...and yes, I know all of this would be much better using assembly and such, but
that is not currently in my wheelhouse (it's something I intend to look at more
in the future, though).

-- Andrew L. Ayers @ September 3rd, 2025



